home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc / Developer Documentation / Recipes, Tech Notes & Articles / Tech Notes / Keeping Saved Windows On-Screen < prev    next >
Encoding:
Text File  |  1996-07-19  |  5.3 KB  |  101 lines  |  [TEXT/ttxt]
  1. OpenDoc™ Technical Note
  2.  
  3. Keeping Saved Windows On-Screen
  4. By The OpenDoc Design Team
  5. July 17, 1996
  6.  
  7.  
  8. © 1996  Apple Computer, Inc. All Rights Reserved.
  9. Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
  10. Mac and OpenDoc are trademarks of Apple Computer, Inc.
  11.  
  12.  
  13. The Problem
  14.  
  15. When an OpenDoc document is saved, all of its open windows are externalized to the document file so that they can be recreated with the same properties (including position and size) the next time the user opens the document.  However, when a document is opened, the saved window may be entirely off-screen if the montor configuration has changed.  This can occur when the resolution of a monitor has been reduced, when a monitor has been removed altogether, or when the document is saved on one system and opened on a different one.
  16.  
  17. Because part editors are responsible for the creation of windows for their root frames, part developers must make sure that each window internalized from storage is opened on-screen.  OpenDoc's Window Utility functions can be used by part developers to easily access a window's externalized properties.  However, these utilities will not validate or alter a window's position or size.  Validation can only be done by the part editor because only the part editor knows where to move an off-screen window.  For example, several windows may need to be moved if a part editor requires fixed relative positioning for the windows.
  18.  
  19.  
  20. The Solution
  21.  
  22. Before creating a saved window, your part editor should validate the window's position relative to the available screen region.  In general, the minimum requirement is to have part of the window's drag region (title bar) on-screen.  This allows the user to reposition the window and, if necessary, click on the zoom box to shrink an oversized window down to the main screen size.  The following sample code is extracted from SamplePart, a basic OpenDoc part editor written by the OpenDoc sample code team.  This method, GetSavedWindowProperties, uses the Window Utilities function BeginGetWindowProperties to read the saved properties of a window.  It then validates the window's position, changing the boundsRect of the window properties so that the window will be visible.  Callers of GetSavedWindowProperties can then use the validated window properties as parameters to the Macintosh toolbox routine NewCWindow.
  23.  
  24.  
  25. #include <WinUtils.h>
  26.  
  27. WindowProperties* SamplePart::GetSavedWindowProperties(
  28.     Environment* ev,
  29.                 ODFrame* frame )
  30. {
  31.     SOM_Trace("SamplePart","GetSavedWindowProperties");
  32.  
  33.        WindowProperties* windowProperties = new WindowProperties;
  34.     
  35.        // If we fail to load the window properties from storage, delete
  36.        // the structure so the calling code will behave appropriately.    
  37.        if ( BeginGetWindowProperties(ev, frame, windowProperties) )
  38.        {    
  39.               // Note: We don't call EndGetWindowProperties because it releases the
  40.               // source frame, which we will need after this method returns.
  41.         
  42.               // Get the part's name to use for the new window.
  43.               TempODIText windowName = GetPartName(ev, fSelf, kSamplePartCategory);
  44.               // Convert the ODIText into a Pascal string.
  45.               GetITextString(windowName, windowProperties->title);
  46.     
  47.               // Verify the window is still visible on a monitor.
  48.         
  49.               RgnHandle windowRgn = ODNewRgn();
  50.               ODBoolean repositionWindow = kODFalse;
  51.         
  52.               // We are only concerned with the window's title bar being
  53.               // visible, so calcuate the titlebar rect from the current
  54.               // window bounds.
  55.               Rect adjustedBounds = windowProperties->boundsRect;
  56.               adjustedBounds.bottom = adjustedBounds.top;
  57.               adjustedBounds.top -= kMacWindowTitleBarHeight;  // Currently 20 pixels
  58.         
  59.               // Intersect the monitor's region
  60.               RectRgn(windowRgn, &adjustedBounds);
  61.               SectRgn(windowRgn, GetGrayRgn(), windowRgn);
  62.         
  63.               if ( !EmptyRgn(windowRgn) )
  64.               {
  65.                      // If the visible portion of the window is too small, we need
  66.                      // to reposition it.
  67.                      Rect intersectedBounds = (**windowRgn).rgnBBox;
  68.                      if ( (intersectedBounds.right-intersectedBounds.left < kMinHorzVisPortion) ||
  69.                                 (intersectedBounds.bottom-intersectedBounds.top < kMinVertVisPortion) )
  70.                            repositionWindow = kODTrue;
  71.         }
  72.               else
  73.               {
  74.                      // If the window is completely offscreen, we need to reposition it.
  75.                      repositionWindow = kODTrue;
  76.               }
  77.               ODDisposeHandle((ODHandle)windowRgn);
  78.         
  79.               // If not, we need to move it so the user can see it.
  80.               if ( repositionWindow )
  81.               {
  82.                      Rect windowRect = (windowProperties->boundsRect);
  83.                      // Move the window to {0,0} coordinates.
  84.                      OffsetRect(&windowRect, -windowRect.left, -windowRect.top);
  85.                      // Now move the window to the default window position.
  86.                      OffsetRect(&windowRect, kALittleNudge, GetMBarHeight() + kMacWindowTitleBarHeight);
  87.                      // Save the new window position in our windowProperties.
  88.                      windowProperties->boundsRect = windowRect;
  89.               }
  90.        }
  91.        else
  92.        {
  93.               // If we were unable to re-load window properties, dispose of the
  94.               // struct.
  95.               ODDeleteObject(windowProperties);
  96.         windowProperties = kODNULL;
  97.        }
  98.         
  99.        return windowProperties;
  100. }
  101.